From c301f0bf78a6e0d37bd3b71f5ac7c6b517331c14 Mon Sep 17 00:00:00 2001 From: Bob Date: Tue, 29 Sep 2026 16:20:13 +0000 Subject: [PATCH 1/8] docs(research): add Research Edition page for researchers --- src/research/index.rst | 8 ++- src/research/research-edition.rst | 101 ++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+), 3 deletions(-) create mode 100644 src/research/research-edition.rst diff --git a/src/research/index.rst b/src/research/index.rst index 9029ac8..dc87e36 100644 --- a/src/research/index.rst +++ b/src/research/index.rst @@ -15,9 +15,10 @@ Why researchers use it automatically. The participant creates an export file and uploads it deliberately, which makes the data flow easy to describe in an ethics application. - **Open source.** The collection logic can be read, audited and cited by reviewers. -- **Cross-platform.** Windows, macOS and Linux, plus Android. -- **Category-only collection.** The Research Edition can be configured to store predefined - categories rather than window titles or URLs. +- **Cross-platform.** Windows, macOS and Linux today; Android is in development. +- **No titles or URLs.** The Research Edition converts browser activity into predefined + categories and discards window titles and URLs before storing anything. + See :doc:`research-edition`. Self-reported computer use is a poor measure of actual computer use. The canonical validity study found that self-report agreed with software registration for only 18% of participants, @@ -85,5 +86,6 @@ instrument, and we keep a list of studies that have used ActivityWatch. .. toctree:: :maxdepth: 2 + research-edition participant-instructions participant-instructions-android diff --git a/src/research/research-edition.rst b/src/research/research-edition.rst new file mode 100644 index 0000000..affddfc --- /dev/null +++ b/src/research/research-edition.rst @@ -0,0 +1,101 @@ +.. _research-edition: + +Research Edition +================ + +The **Research Edition** is a separate build of ActivityWatch for research studies. It +records which applications participants use and for how long, converts browser activity into +categories defined by the study, and discards window titles and URLs before anything is +written to disk. Data stays on the participant's computer until they export it and send it +to the study team. + +This page is for researchers deciding whether it fits their study. Participants should use +the :doc:`participant instructions `. + +.. note:: + *Last reviewed: 2026-09-30, against v0.14.0b5-research.* Desktop builds are + **prereleases**. Read the platform status below before planning around a platform. + +What it collects +---------------- + +The desktop Research Edition turns on a privacy filter in ``aw-watcher-window`` +(``research_enabled = true``): + +- **Browsers**: each browser window is classified into a study category by matching the URL + (where available) and otherwise the window title against the study's category map. The + longest matching pattern wins. Windows that match nothing are stored as ``excluded``. The + title and URL are discarded **before** the event is recorded, not at export. +- **Other applications**: the window title is discarded. The **application name is kept**. + A variant can instead replace application names with categories by setting the optional + ``research_app_category_map``. Unmapped apps then become ``Excluded``. +- **Away from computer**: recorded by the regular AFK watcher. +- **Export**: the participant's computer name is rewritten to ``research-participant``. The + export refuses to run if the database contains unfiltered events, for example when the + Research Edition was installed over an existing ActivityWatch database. + +What is *not* collected: page titles, URLs, document names and window titles. What *is* +visible in the current build: application names, including which browser was used. + +There is no telemetry and no study server. The participant exports one JSON file from the +dashboard and uploads it where the study team asks. + +Keeping participant and study data apart +---------------------------------------- + +The Research Edition has its own app identity, its own data folder and its own server port +(**5667**, against **5600** for a standard install). A participant who already uses +ActivityWatch can run both side by side, and the standard install's data is not read or +changed. The dashboard shows a **Research Edition** badge. + +Making a variant for your study +------------------------------- + +Studies tend to want the same thing: categorized time, no raw titles or URLs, a simple +end-of-study export. A variant is therefore mostly: + +1. **A category map**: which sites and apps belong to which of your categories, with + everything else excluded. This is the part only the study can define. +2. **A tagged build**: research builds are published as GitHub prereleases with a + ``-research`` tag, which gives participants a stable download link you can cite in a + methods section. +3. **A participant guide and export step**: start from the + :doc:`participant instructions ` and add your study name, + contact details and upload location. + +The design is intended to fit an ethics review, but your committee decides that for your +study. Bring its requirements when you get in touch. + +To request a variant, contact Erik Bjäreholt, the ActivityWatch maintainer, at +erik@bjareho.lt. + +Platform status +--------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - Platform + - Status + - Notes + * - Windows, macOS, Linux + - Shipped as prereleases + - Latest: `v0.14.0b5-research + `_. + The participant instructions cover Windows and macOS. + * - Android + - In development + - ``aw-android`` has a ``research`` build flavor with its own application ID + (``net.activitywatch.android.research``) and port 5667, so it installs beside the + regular app. The category filter that the desktop build has is **not** on Android + yet, and no ``-research`` Android release has been published. See the + :doc:`Android participant instructions ` for the + intended install path. + * - iPhone and iPad + - Planned + - There is no iOS app. `aw-import-screentime + `_ imports Apple's Screen Time + data into ActivityWatch. It requires a Mac with Screen Time "Share Across Devices" + enabled on both devices under the same Apple account, and Full Disk Access on the Mac. + It is a standalone tool, and the research filter does not apply to that data path yet. From 410e79aafbcbe0721bde3fcade6c75860921f922 Mon Sep 17 00:00:00 2001 From: Bob Date: Tue, 29 Sep 2026 16:23:57 +0000 Subject: [PATCH 2/8] docs(research): add data size estimate to Research Edition page --- src/research/research-edition.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/research/research-edition.rst b/src/research/research-edition.rst index affddfc..7c83d3c 100644 --- a/src/research/research-edition.rst +++ b/src/research/research-edition.rst @@ -48,6 +48,12 @@ The Research Edition has its own app identity, its own data folder and its own s ActivityWatch can run both side by side, and the standard install's data is not read or changed. The dashboard shows a **Research Edition** badge. +Data size +--------- + +The export is small: roughly 1-5 MB per participant per week of collection, as an +estimate. + Making a variant for your study ------------------------------- From 641875e52011ee6cb14f62dc0e969b19a837be14 Mon Sep 17 00:00:00 2001 From: Bob Date: Tue, 29 Sep 2026 17:50:52 +0000 Subject: [PATCH 3/8] docs(research): qualify collection guarantee and category maps Scope the no-titles/URLs claim to aw-watcher-window and warn that extra watchers can still store URLs. Distinguish the browser category map from the optional research_app_category_map, which is what actually hides unmapped app names. Git-Session-Id: fd976f58-24ed-5526-8cd7-235d83bc0a3d --- src/research/index.rst | 6 +++--- src/research/research-edition.rst | 26 ++++++++++++++++++-------- 2 files changed, 21 insertions(+), 11 deletions(-) diff --git a/src/research/index.rst b/src/research/index.rst index dc87e36..0f33433 100644 --- a/src/research/index.rst +++ b/src/research/index.rst @@ -16,9 +16,9 @@ Why researchers use it makes the data flow easy to describe in an ethics application. - **Open source.** The collection logic can be read, audited and cited by reviewers. - **Cross-platform.** Windows, macOS and Linux today; Android is in development. -- **No titles or URLs.** The Research Edition converts browser activity into predefined - categories and discards window titles and URLs before storing anything. - See :doc:`research-edition`. +- **Filtered titles and URLs.** The bundled window watcher converts browser activity into + predefined categories and discards window titles and URLs before storing them. + Additional watchers are outside that guarantee. See :doc:`research-edition`. Self-reported computer use is a poor measure of actual computer use. The canonical validity study found that self-report agreed with software registration for only 18% of participants, diff --git a/src/research/research-edition.rst b/src/research/research-edition.rst index 7c83d3c..6ee92cb 100644 --- a/src/research/research-edition.rst +++ b/src/research/research-edition.rst @@ -4,10 +4,10 @@ Research Edition ================ The **Research Edition** is a separate build of ActivityWatch for research studies. It -records which applications participants use and for how long, converts browser activity into -categories defined by the study, and discards window titles and URLs before anything is -written to disk. Data stays on the participant's computer until they export it and send it -to the study team. +records which applications participants use and for how long. The bundled window watcher +converts browser activity into categories defined by the study and discards window titles +and URLs before those events are written to disk. Data stays on the participant's computer +until they export it and send it to the study team. This page is for researchers deciding whether it fits their study. Participants should use the :doc:`participant instructions `. @@ -34,8 +34,15 @@ The desktop Research Edition turns on a privacy filter in ``aw-watcher-window`` export refuses to run if the database contains unfiltered events, for example when the Research Edition was installed over an existing ActivityWatch database. -What is *not* collected: page titles, URLs, document names and window titles. What *is* -visible in the current build: application names, including which browser was used. +On the ``aw-watcher-window`` path, page titles, URLs, document names and window titles +are not stored. What *is* visible in the current build: application names, including +which browser was used. + +That guarantee does not cover other watchers. The Research Edition server stores whatever +is sent to it. A default install does not ship ``aw-watcher-web``, but if a participant +connects it (or any other URL-bearing watcher) to port 5667, those events keep titles and +URLs and sit in the same export. Studies should tell participants not to add extra +watchers. There is no telemetry and no study server. The participant exports one JSON file from the dashboard and uploads it where the study team asks. @@ -60,8 +67,11 @@ Making a variant for your study Studies tend to want the same thing: categorized time, no raw titles or URLs, a simple end-of-study export. A variant is therefore mostly: -1. **A category map**: which sites and apps belong to which of your categories, with - everything else excluded. This is the part only the study can define. +1. **Category maps**: a browser map that defines which sites belong to the study's + categories (unmatched browser windows are stored as ``excluded``). Application names + are kept by default. To replace them with categories and mark unmapped apps as + ``Excluded``, configure the optional ``research_app_category_map``. This is the part + only the study can define. 2. **A tagged build**: research builds are published as GitHub prereleases with a ``-research`` tag, which gives participants a stable download link you can cite in a methods section. From 11641d2e33c9587b5fdd674670c708ee6f6d5478 Mon Sep 17 00:00:00 2001 From: Bob Date: Tue, 29 Sep 2026 18:59:11 +0000 Subject: [PATCH 4/8] docs(research): drop unmeasured export-size range The 1-5 MB per participant-week figure had no measurement. Extra watchers also grow the JSON export, so a published range would mislead storage and upload planning. Point studies at a pilot-week measurement instead. Git-Session-Id: 24cde253-57d2-5213-b103-f7669205f12d --- src/research/research-edition.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/research/research-edition.rst b/src/research/research-edition.rst index 6ee92cb..ae29881 100644 --- a/src/research/research-edition.rst +++ b/src/research/research-edition.rst @@ -58,8 +58,12 @@ changed. The dashboard shows a **Research Edition** badge. Data size --------- -The export is small: roughly 1-5 MB per participant per week of collection, as an -estimate. +The JSON export from a default Research Edition install is typically small: +window and AFK events with titles and URLs already dropped, so the file is +mostly short category strings. Extra watchers connected to port 5667 add their +own buckets to the same export. Studies that need a number for a data-protection +review should measure a pilot-week export rather than plan around a published +range. Making a variant for your study ------------------------------- From 91fbfc5b20e730af93b5bb9172187ac92158a057 Mon Sep 17 00:00:00 2001 From: Bob Date: Tue, 29 Sep 2026 19:03:30 +0000 Subject: [PATCH 5/8] docs(research): restore size estimate, reword ethics sentence --- src/research/research-edition.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/research/research-edition.rst b/src/research/research-edition.rst index ae29881..9f5dc73 100644 --- a/src/research/research-edition.rst +++ b/src/research/research-edition.rst @@ -58,7 +58,8 @@ changed. The dashboard shows a **Research Edition** badge. Data size --------- -The JSON export from a default Research Edition install is typically small: +The JSON export from a default Research Edition install is small, on the order of 1-5 MB +per participant per week of collection (an estimate, not a guarantee): window and AFK events with titles and URLs already dropped, so the file is mostly short category strings. Extra watchers connected to port 5667 add their own buckets to the same export. Studies that need a number for a data-protection @@ -83,8 +84,10 @@ end-of-study export. A variant is therefore mostly: :doc:`participant instructions ` and add your study name, contact details and upload location. -The design is intended to fit an ethics review, but your committee decides that for your -study. Bring its requirements when you get in touch. +Ethics committees decide for themselves, but the design is built around data +minimisation: titles and URLs are not stored, nothing is sent live, and the participant +exports a single file they can inspect. Bring your committee's requirements when you get +in touch and the variant can be adjusted to them. To request a variant, contact Erik Bjäreholt, the ActivityWatch maintainer, at erik@bjareho.lt. From 3fe353efbace051eec0223d4200cec324075d9a5 Mon Sep 17 00:00:00 2001 From: Bob Date: Tue, 29 Sep 2026 19:03:44 +0000 Subject: [PATCH 6/8] docs(research): tidy data size paragraph --- src/research/research-edition.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/src/research/research-edition.rst b/src/research/research-edition.rst index 9f5dc73..d70e66f 100644 --- a/src/research/research-edition.rst +++ b/src/research/research-edition.rst @@ -59,12 +59,10 @@ Data size --------- The JSON export from a default Research Edition install is small, on the order of 1-5 MB -per participant per week of collection (an estimate, not a guarantee): -window and AFK events with titles and URLs already dropped, so the file is -mostly short category strings. Extra watchers connected to port 5667 add their -own buckets to the same export. Studies that need a number for a data-protection -review should measure a pilot-week export rather than plan around a published -range. +per participant per week of collection (an estimate, not a guarantee). It holds window and +AFK events with titles and URLs already dropped, so most of it is short category strings. +Extra watchers connected to port 5667 add their own buckets to the same export. Studies that +need a firm number for a data-protection review should measure a pilot-week export. Making a variant for your study ------------------------------- From 0e86df5c730d3a81b36cf35e59801c277b1d7561 Mon Sep 17 00:00:00 2001 From: Bob Date: Tue, 29 Sep 2026 19:05:30 +0000 Subject: [PATCH 7/8] docs(research): drop numeric export-size range again A sibling restore put the unmeasured 1-5 MB figure back. Greptile's P2 is that researchers must not plan storage around an unpublished measurement. Keep the extra-watcher caveat and the pilot-week measurement guidance. Git-Session-Id: 24cde253-57d2-5213-b103-f7669205f12d --- src/research/research-edition.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/research/research-edition.rst b/src/research/research-edition.rst index d70e66f..4091e29 100644 --- a/src/research/research-edition.rst +++ b/src/research/research-edition.rst @@ -58,11 +58,11 @@ changed. The dashboard shows a **Research Edition** badge. Data size --------- -The JSON export from a default Research Edition install is small, on the order of 1-5 MB -per participant per week of collection (an estimate, not a guarantee). It holds window and -AFK events with titles and URLs already dropped, so most of it is short category strings. -Extra watchers connected to port 5667 add their own buckets to the same export. Studies that -need a firm number for a data-protection review should measure a pilot-week export. +The JSON export from a default Research Edition install is typically small. It +holds window and AFK events with titles and URLs already dropped, so most of it +is short category strings. Extra watchers connected to port 5667 add their own +buckets to the same export. Studies that need a firm number for a +data-protection review should measure a pilot-week export. Making a variant for your study ------------------------------- From dfdc188347aec194dbbba45543b7351badfeb8b6 Mon Sep 17 00:00:00 2001 From: Bob Date: Tue, 29 Sep 2026 20:13:57 +0000 Subject: [PATCH 8/8] docs(research): describe export as filtered window and AFK events MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Greptile P2: "mostly short category strings" understated the all-bucket JSON. Name the actual contents — filtered window events and AFK events, each with timestamp and duration, window events keeping app names and study categories — and keep the extra-watcher caveat plus the pilot-week measurement line. Git-Session-Id: d5e38c4c-8308-564d-8a10-cb3ae24c26d6 --- src/research/research-edition.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/research/research-edition.rst b/src/research/research-edition.rst index 4091e29..3bbf4e0 100644 --- a/src/research/research-edition.rst +++ b/src/research/research-edition.rst @@ -59,10 +59,11 @@ Data size --------- The JSON export from a default Research Edition install is typically small. It -holds window and AFK events with titles and URLs already dropped, so most of it -is short category strings. Extra watchers connected to port 5667 add their own -buckets to the same export. Studies that need a firm number for a -data-protection review should measure a pilot-week export. +is an all-bucket export of filtered window events and AFK events. Each event +has a timestamp and duration; window events keep the application name and the +study category, with titles and URLs already dropped. Extra watchers connected +to port 5667 add their own buckets to the same export. Studies that need a +firm number for a data-protection review should measure a pilot-week export. Making a variant for your study -------------------------------