# Project pack: ActivityWatch @ c8b9203

Facts about **ActivityWatch** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> ActivityWatch quietly records which apps and websites you use and when you are away, then shows it in a local web dashboard. Nothing leaves your computer. You can add rules to group activity into categories such as work and leisure, and use the data for time reports or healthier habits.

## Version and source
- Repository: https://github.com/ActivityWatch/activitywatch
- Pinned commit: `c8b9203be894b690c00d317e59d7fb3ab6658af4`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/ActivityWatch/activitywatch/archive/c8b9203be894b690c00d317e59d7fb3ab6658af4.zip
- Official docs: https://docs.activitywatch.net
- Licence: **MPL-2.0**. Free to use and change. If you share a changed version of a file covered by this licence, you must share that file's source under the same licence. Using it privately has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/ActivityWatch/activitywatch bespoke-activitywatch
  cd bespoke-activitywatch
  git checkout --detach c8b9203be894b690c00d317e59d7fb3ab6658af4
  # Prepare development requirements and local configuration first.
  git submodule update --init --recursive
  make build
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  Download the installer for Windows, macOS or Linux from https://activitywatch.net/downloads, then open http://localhost:5600.
  ```

- Needs: A desktop download for everyday use; Python 3.9+, Node and Rust for development
- Develop: `make build`
- Test: `make test`
- Stack: rust, python, typescript (Rust server, Vue, Tauri). Difficulty for a non-developer with an AI: **moderate**. A collection of small repositories (server, watchers, web UI) pulled together here as submodules. Categories and rules need no code; new watchers are small Python or Rust programs.

## Customisation points (settings → extend → code)
- **categories** [settings]: Group apps and sites into Work, Break, Learning and more. → `http://localhost:5600 → Settings → Categorization`
- **watchers** [settings]: Turn on or off the window, away-from-keyboard and web watchers. → `aw-qt tray menu → modules`
- **query-api** [extend]: Pull your data into your own reports. → `http://localhost:5600/api and the aw-client library`
- **new-watcher** [extend]: Track something new, such as a game or a code editor. → `aw-client examples, the aw-watcher-* folders`
- **web-ui** [code]: New views and charts. → `the aw-webui repo, pulled in by the make build`

## Must keep working
- Data stays local. Don't add outbound uploads without clear opt-in.
- The event and bucket formats, so existing data stays readable.
- The watchers' permissions on macOS and Linux.

## Staying updatable
Use categories, the query API and separate scripts. Write new watchers as separate small programs instead of changing the core.

## Data, costs and safety
- Personal data: **yes**. Stored in: A local SQLite database in your user data folder. Window titles and web page titles can reveal private information. Review categories before sharing any data.
- It records window titles and web page titles, which may contain private details. Check what it records.
- The local web server is on port 5600. Don't expose it to the internet.

---

# Customising ActivityWatch

ActivityWatch is a family of small programs. Most personalisation is category rules and queries. For bigger changes you write a new watcher or a script that reads the local API.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Server (stores events) | aw-server-rust/ (and the older aw-server/) |
| Core types and helpers | aw-core/ |
| Client library for scripts | aw-client/ |
| Window and away-from-keyboard watchers | aw-watcher-window/, aw-watcher-afk/ |
| Tray launcher | aw-qt/ and aw-tauri/ |
| Notifications | aw-notify/ |
| Build and packaging | Makefile and scripts/ |

## Use the gentlest change first

1. **Settings (no code):** categories, which watchers are on, and the idle timeout.
2. **Extend:** scripts with `aw-client`, or a new watcher.
3. **Code:** the server or the web UI.

## Recipes

- **Weekly report:** use `aw-client` to query last week's events by category and format them.
- **New watcher:** create a small program that sends heartbeat events into its own bucket using `aw-client`.

## Running and checking your changes

- Run the server and open http://localhost:5600 to confirm events appear.
- `make test` runs the test suites for the pieces you built.
- Test watchers with a throwaway bucket name so real data stays clean.

## Pitfalls

- Many folders are separate Git repositories (submodules). Initialise them first.
- On macOS and Wayland the window watcher needs special permissions.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/activitywatch/c8b9203/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/activitywatch/c8b9203/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/activitywatch/c8b9203/r2/SKILL.md)