Document privacy-first ActivityWatch workflows for agents and AI

[TimeToBuildBob]

Context

Follow-up from ActivityWatch/aw-webui#922. The built-in dev-mode summary is deliberately basic and provider-key based. Users who outgrow it need a privacy-first path for using ActivityWatch data with agents and analysis tools, grounded in the existing exporting/query docs and the canonical query rather than implying that uploading raw events to a hosted LLM is the recommended workflow.

Scope

Extend the documentation near the querying-data guide with an "ActivityWatch with agents/AI" guide that covers:

• choosing between export, the HTTP API, AQL/query explorer, and MCP/agent tooling
• starting from the canonical AFK-filtered query and category rules
• minimizing data before model access (aggregate locally; avoid raw titles/URLs by default)
• local-model and existing-subscription workflows before direct third-party API-key upload
• a small provider-neutral compact context example
• privacy/threat-model guidance and an explicit review-before-send step
• links from the export/analysis docs and from the dev-mode activity-analysis page

Acceptance criteria

• A user can reproduce a bounded, AFK-filtered activity summary from documented commands/queries
• The guide distinguishes local processing, agent/tool access, and third-party provider upload
• Sensitive fields and safe aggregation defaults are explicit
• At least one local-first workflow and one general agent integration workflow are shown
• Relevant exporting, querying, categorization, and API docs cross-link the guide
• feat(ai-summary): add client-side AI activity summary page aw-webui#922 links to the most relevant published page (the query guide remains the temporary link)

This documentation should describe a general workflow, not endorse one LLM vendor or require the prototype UI.

[ErikBjare]

@TimeToBuildBob Not the first time we discussed this, look up previous mentions in your task files etc around AW strategy.

[TimeToBuildBob]

Seen. Investigating now; I'll reply here with the concrete work, task, or handoff once it's done.

[TimeToBuildBob]

You're right — this was already a named strategy lane, not a fresh idea. I found and reconciled the existing activitywatch-ai-agent-enablement-docs task and knowledge/strategic/2026-profitability-plan.md WS6, both from July 8. I moved that task from the old “waiting for AW-repo greenlight” gate to todo, made this issue its canonical tracking thread, and committed the reconciliation as a1b5b6821a.

The prior strategy is more specific than my initial issue framing: survey signal says the headline should be local, privacy-preserving categorization and summaries — not generic agent/chatbot positioning. The docs layer should start from aw-client canonical / canonical AFK filtering, aggregate and inspect locally before model access, and distinguish local models or existing agent/subscription workflows from direct API upload. Existing work to reuse as patterns includes gptme-activity-summary, the AW day-narrative prototype, aw-mcp, and the dev-mode aw-webui#922; none should be presented as the canonical product.

I also ran the idempotent promotion helper; it now resolves to that established task instead of creating a second actionable task. Next deliverable is the docs PR against this issue, using those prior boundaries rather than inventing another AW/AI strategy.

[TimeToBuildBob]

Docs PR opened: ActivityWatch/docs#176.

What it does:

• adds an "ActivityWatch with agents and AI" guide near the data/query examples
• starts from canonical events, AFK filtering, and configured categories
• documents aggregate-before-inference, review-before-send, sensitive-field defaults, local-first workflows, general agent/tool access, and third-party provider upload boundaries
• cross-links from querying data, exporting data, categorization, REST API, and the examples index

Validation: poetry install && make html passed in the docs checkout. The build still has existing repo warnings unrelated to the new page (changelog labels, missing media, missing aw_qt, unknown :docs: roles, Graphviz), but nothing points at the new guide or changed links.

I moved the local task to waiting on ActivityWatch/docs#176. After merge, the remaining acceptance step is linking the published page from ActivityWatch/aw-webui#922 and then rechecking this issue before closing.

[TimeToBuildBob]

ActivityWatch/docs#176 has been merged — the initial privacy-first AI agent workflows guide is now in the docs repo. The guide covers canonical AFK-filtered event queries, local aggregation, bounded payload review before sending to a model, and the local-first vs. hosted-inference distinction aligned with the strategy in this issue.

Remaining work tracked in the linked follow-up issues:

• Improve the single-pass activity-analysis context aw-webui#925 — richer bounded single-pass context (AFK-filtered active time, window titles, domains, temporal/focus stats)
• This issue itself — broader docs pass and more usage patterns

Marking the activitywatch-ai-agent-enablement-docs task as done in Bob's workspace since the initial deliverable (docs PR) is shipped.