Conversation
ActivityWatch is used as a data-collection instrument in academic studies, but the participant-facing instructions have been circulated over email and go stale between releases. This adds a canonical, versioned page studies can link to. - research/index: why the tool suits research (local-first, auditable, category-only collection), the IJmker 2008 validity citation, and how to cite ActivityWatch via the Zenodo DOI - research/participant-instructions: install and permissions per platform, what is recorded, and the end-of-study export, plus a "Notes for researchers" section covering the mistakes that generate support mail (the per-row export menu instead of "Export all buckets as JSON", CSV vs JSON, two buckets being normal, and the UI auto-selecting a locale from the browser language) Studies keep their own branding, upload location and translations; only the mechanics live here.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| - **Two buckets is correct**, not a symptom of a double installation: one window watcher and | ||
| one AFK watcher. Four rows would mean the participant opened the standard dashboard on port | ||
| 5600 instead. |
There was a problem hiding this comment.
Port 5600 serves the standard installation’s separate bucket set; it does not add two rows to the Research Edition’s data. Optional watchers can also create four or more legitimate rows on either server. This fixed row-count test could therefore misidentify a valid Research Edition session or fail to recognize the standard dashboard. Diagnose the edition using the port and Research Edition badge instead.
| - **Two buckets is correct**, not a symptom of a double installation: one window watcher and | |
| one AFK watcher. Four rows would mean the participant opened the standard dashboard on port | |
| 5600 instead. | |
| - **Two buckets is correct** for the default Research Edition setup: one window watcher and | |
| one AFK watcher. Additional watchers may create more rows, so use the **Research Edition** | |
| badge and port 5667—not the row count—to distinguish it from the standard dashboard. |
Knowledge Base Used:
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0254b612c9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - **Two buckets is correct**, not a symptom of a double installation: one window watcher and | ||
| one AFK watcher. Four rows would mean the participant opened the standard dashboard on port | ||
| 5600 instead. |
There was a problem hiding this comment.
Opening port 5600 queries only the standard server; it does not merge the buckets served on port 5667. Bucket count is also not fixed: the documented data model creates one bucket per watcher and host (src/buckets-and-events.rst:7-13), so a hostname change or an additional watcher can produce four rows, while a standard installation may show only the two core buckets. This guidance can therefore misdiagnose the correct Research dashboard; use the port or Research Edition badge as the discriminator instead.
Useful? React with 👍 / 👎.
|
Reviewed the Research section, with attention on "Notes for researchers" (that list came out of the Lund instruction reviews). The notes are the right support-mail generators: Export-all vs per-row, JSON vs CSV, locale auto-select, fixed filename, live Raw Data unsanitised. Put the unsanitised-live-Raw-Data warning first. Researchers on a support call will open the dashboard, see real titles, and think the ethics filter is broken. The rewrite to One correction, same line Greptile/Codex flagged:
That is wrong, and extra-watchers is the smaller reason. The standard dashboard on 5600 also has two buckets (window + AFK). Opening 5600 does not add two rows to the 5667 view — they are different servers. Row count does not distinguish editions at all. Diagnose by the Research Edition badge and port 5667. Two rows is the expected default for a participant; it is not a discriminator. Four rows is a different failure mode (hostname change, extra watcher, or they exported the wrong server and something else is also installed). Suggested replacement:
Otherwise this is the page studies should link to instead of emailing a copy. I would not block on Android: Windows unsigned / SmartScreen is documented. Keep it. That friction repeats on every study until the installer is signed. |
ActivityWatch appears in methods sections rather than titles or abstracts, so it is largely invisible to citation indexes - both Zenodo DOIs currently report zero tracked citations despite real academic use, including a 2,000-participant Oxford study and a multi-year ERC-funded deployment at Ghent. A public list serves two purposes: it lets researchers choosing an instrument see prior use, and it gives existing users a reason to tell us they exist.
|
The studies list is the right addition — methods-section uses are invisible to indexes, and this is how they become visible. One correction on The rest checks out: Ballou et al. Stage 1 RR is real; Parry & Klingelhoefer name AW as an exemplar desktop logger; Rivera/Booz/Hammerstein (CMU SEI, ECCWS 2025) actually instrument with AW. The two notes-for-researchers edits from the previous comment are still outstanding on Optional miss, not blocking: Timár (Masaryk, 2025) is a thesis that actually builds on AW. |
2 participants
ActivityWatch is used as a data-collection instrument in academic studies. Until now the participant-facing instructions have been written per-study and circulated over email, which means they go stale between releases: the current round of review caught a study's instructions still describing pre-
b5autostart behaviour, pointing participants at the per-bucket export menu instead of "Export all buckets as JSON", and assuming an English-only UI.This adds a canonical, versioned page that studies can link to instead of maintaining their own copy of the mechanics.
What's here
research/index— why the tool fits research use (local-first, auditable, category-only collection), the canonical validity citation for why self-reported computer use is a poor measure (IJmker et al. 2008: self-report agreed with registration for only 18% of participants), and how to cite ActivityWatch via the Zenodo DOI.research/participant-instructions— install and permissions per platform, what is and isn't recorded, and the end-of-study export. Plus a "Notes for researchers" section covering the things that reliably generate support mail:Studies keep their own branding, upload location, ethics wording and translations. Only the mechanics live here, since those are what change between releases.
Notes
v0.14.0b5-researchbuild and the source at that tag.