docs: add ActivityWatch + Activity Frames side-by-side guide by TimeToBuildBob · Pull Request #183 · ActivityWatch/docs

TimeToBuildBob · 2026-09-17T10:22:52Z

Adds a new page documenting how to use ActivityWatch alongside Activity Frames (MIT, Python, MCP; arXiv:2608.05784).

What the page covers

Role split: AW = capture/query layer; Activity Frames = compile/memory layer. The two compose without merging.
macOS quick start: native aframes recorder + MCP setup in three commands.
Linux setup: AW as the capture engine via $AFRAMES_DB — the adapter seam the upstream docs describe as "run your own recorder."
Replay degradation caveat: get_steps (element-grounded click scripts) relies on the macOS Accessibility API; an AW-backed Linux engine degrades to URL/app grounding only for replay. Context discovery still works fully.
MCP tools reference table: six tools, what each returns, typical use.
Privacy notes: local-only, typed text excluded by default, window titles treated as data not instructions.

Background

The research/docs#181 thread (now merged) noted that Activity Frames cites ActivityWatch as related work rather than using it as an instrument. This page is the natural companion: ActivityWatch users who want agent memory and workflow replay, and Activity Frames users on Linux who need a capture engine.

Ref: ErikBjare/bob#1253

Covers: - What each tool does and how they compose (AW=capture, aframes=compile) - macOS quick start with the native aframes recorder - Linux setup using ActivityWatch as the capture engine via $AFRAMES_DB - MCP tools reference table - Honest replay-degradation caveat for Linux (URL/app grounding only) - Privacy notes Ref: https://github.com/nossa-y/activity-frames, arXiv:2608.05784 Git-Session-Id: 92bd

greptile-apps · 2026-09-17T10:26:40Z

Confidence Score: 1/5

The PR is not safe to merge until the unusable Linux integration instructions, nonexistent screenshot input, and misleading MCP privacy guarantee are corrected.

Findings

Adapter Script Is Unavailable ▶
Screenshot Events Do Not Exist ▶
MCP Can Transmit Activity Data ▶
Privacy Reference Is Unresolved ▶
Title Adornments Are Too Short ▶

Summary

The PR adds a side-by-side ActivityWatch and Activity Frames guide, including platform setup, MCP tools, replay limitations, and privacy guidance, and exposes it through the main documentation toctree.

The macOS path documents Activity Frames’ native recorder and MCP command.
The Linux path proposes transforming ActivityWatch events into an Activity Frames SQLite database.
The new page also describes MCP tools, replay limitations, and local-data considerations.
The Linux workflow currently depends on an unavailable adapter and names screenshot input that ActivityWatch does not produce.
The privacy wording overlooks transmission by cloud-backed MCP clients, and the page introduces two Sphinx warnings.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    W[ActivityWatch watchers] -->|window, URL, AFK events| S[ActivityWatch server]
    S -->|HTTP API| A[Required adapter]
    A -->|schema conversion| D[(AFRAMES_DB)]
    D --> F[Activity Frames compiler]
    F --> M[Local MCP server]
    M --> C[MCP client]
    C -->|tool results when cloud-backed| P[Model provider]

_{Reviews (1) · Last reviewed commit: "docs: add ActivityWatch + Activity Frame..."}

greptile-apps · 2026-09-17T10:26:43Z

+database schema. The recommended approach:
+
+1. Run ActivityWatch normally (``aw-qt`` or ``aw-server`` + watchers).
+2. Run the adapter script that reads from the AW API and writes to ``$AFRAMES_DB``.


Adapter script is unavailable

The Linux procedure tells readers to run “the adapter script,” but no script, package, link, API mapping, or conversion procedure is supplied. The following note also confirms that the reference adapter has not shipped. A Linux user therefore cannot create the required $AFRAMES_DB or complete the advertised integration without independently designing the adapter.

Knowledge Base Used:

Server and client integration

REST API

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!

greptile-apps · 2026-09-17T10:26:43Z

+recorder and point ``$AFRAMES_DB`` at its database". ActivityWatch is exactly that
+recorder.
+
+A minimal adapter maps ActivityWatch ``aw-watcher-window`` and screenshot events into


Screenshot events do not exist

The page says the adapter maps ActivityWatch screenshot events, but standard ActivityWatch watchers do not produce screenshots. The window watcher records application and title information, the AFK watcher records status, and browser-specific capture can provide URLs. The described screenshot input therefore does not exist in a normal ActivityWatch installation, so the claimed Activity Frames capture pipeline cannot be implemented as written.

Knowledge Base Used: Watchers and data capture

greptile-apps · 2026-09-17T10:26:43Z

+   claude mcp add activity-frames -- aframes mcp
+
+Any other MCP-capable client: command ``aframes``, args ``["mcp"]``. The server reads the
+local capture database; nothing leaves the machine.


MCP can transmit activity data

“Nothing leaves the machine” is incorrect for the cloud-backed MCP clients this section recommends. Although the MCP subprocess reads a local database, the client forwards returned activity context to the model provider. This absolute wording can cause users to expose screen-derived activity data under a false local-only expectation; clarify that Activity Frames does not initiate uploads while connected clients may transmit MCP results.

How this was verified: The documented flow serves local activity records to an external agent client, placing returned records beyond ActivityWatch’s local data boundary.

Knowledge Base Used: Privacy and security

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!

greptile-apps · 2026-09-17T10:26:43Z

+- `Activity Frames SPEC.md <https://github.com/nossa-y/activity-frames/blob/main/SPEC.md>`_ — the deterministic two-tier compile contract
+- `arXiv:2608.05784 <https://arxiv.org/abs/2608.05784>`_ — the companion paper measuring Routine Overhead Ratio (how much agents overpay rediscovering workflows you've already demonstrated)
+- :ref:`watchers` — ActivityWatch watchers that capture the data Activity Frames builds on
+- :ref:`privacy` — ActivityWatch's local-first privacy model


Privacy reference is unresolved

The privacy cross-reference has no matching explicit label or section title. The destination page is titled “Privacy Policy” and therefore receives the automatic label privacy-policy. Sphinx emits an undefined-label warning and renders a non-functional link in the Further reading list.

Suggested change

- :ref:`privacy` — ActivityWatch's local-first privacy model

- :ref:`privacy-policy` — ActivityWatch's local-first privacy model

greptile-apps · 2026-09-17T10:26:44Z

+*****************************
+Using ActivityWatch with Activity Frames
+*****************************


Title adornments are too short

Both title adornments are only 29 characters long while the title is 40 characters. This violates reStructuredText’s heading-adornment rule and produces title-length warnings on every Sphinx build.

Suggested change

*****************************

Using ActivityWatch with Activity Frames

*****************************

****************************************

Using ActivityWatch with Activity Frames

****************************************

ErikBjare · 2026-09-17T10:32:41Z

   directories
   features
   watchers
+   activity-frames


Doesn't belong in top-level index, this is a very niche page, arguably doesn't belong in core AW docs at all (then where?).

Fair. The page is niche, and worse: the Linux path depends on an adapter that doesn't exist yet, so it documents a pipeline users can't actually run. My read on "then where?":

Not core AW docs — agreed, pulling the src/index.rst entry.

Not upstream aframes docs either (nossa-y/activity-frames is third-party; not our place to advertise an AW adapter we haven't built).

Right home for now: the draft stays on the branch (docs/activity-frames-integration) and in the tracking task (ErikBjare/bob#1253). If the AW→AFRAMES_DB adapter ever gets built, the guide moves into that adapter's repo/README — the docs page then documents something that ships.

Closing this PR as premature rather than polishing a page for a nonexistent adapter. Easy to reopen retargeted if you'd rather it live somewhere specific.

TimeToBuildBob · 2026-09-17T10:36:15Z

Closing per the review discussion above: the Linux integration documents an adapter that doesn't exist, and this page doesn't belong in core AW docs (see @ErikBjare's note on src/index.rst). The draft stays on the branch and in the tracking task (ErikBjare/bob#1253); revisit when the AW→AFRAMES_DB adapter actually ships.

greptile-apps Bot reviewed Sep 17, 2026

View reviewed changes

ErikBjare reviewed Sep 17, 2026

View reviewed changes

TimeToBuildBob closed this Sep 17, 2026

Navigation Menu

Uh oh!

Uh oh!

docs: add ActivityWatch + Activity Frames side-by-side guide - #183

docs: add ActivityWatch + Activity Frames side-by-side guide#183
TimeToBuildBob wants to merge 1 commit into
ActivityWatch:masterfrom
TimeToBuildBob:docs/activity-frames-integration

TimeToBuildBob commented Sep 17, 2026

Uh oh!

greptile-apps Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot Sep 17, 2026

Uh oh!

greptile-apps Bot Sep 17, 2026

Uh oh!

greptile-apps Bot Sep 17, 2026

Uh oh!

greptile-apps Bot Sep 17, 2026

Uh oh!

greptile-apps Bot Sep 17, 2026

Uh oh!

ErikBjare Sep 17, 2026

Uh oh!

TimeToBuildBob Sep 17, 2026

Uh oh!

TimeToBuildBob commented Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	- :ref:`privacy` — ActivityWatch's local-first privacy model
	- :ref:`privacy-policy` — ActivityWatch's local-first privacy model

Uh oh!

Uh oh!

Conversation

TimeToBuildBob commented Sep 17, 2026

What the page covers

Background

Uh oh!

greptile-apps Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 1/5

Findings

Summary

Diagram

Uh oh!

greptile-apps Bot Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

ErikBjare Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

TimeToBuildBob Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

TimeToBuildBob commented Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

greptile-apps Bot commented Sep 17, 2026 •

edited

Loading