Built-in watchers: how they work

TrackFlow ships with a set of watchers already built in — small background processes that start automatically and need no setup. This page explains what each one tracks, how often it checks, and where to turn it on or off.

If you want to track something these don't cover, see Custom watchers instead — no code changes to TrackFlow required.

All of this data stays on your computer. Nothing described here is ever sent anywhere over the network.

You can turn any of these on or off from Watchers → Data sources.

Active window (`aw-watcher-window`)

The foundation almost everything else is built on. Checks which app and window title is in the foreground about once a second and records it. Powers the General lane in the Timeline and most of the Home summary modules (Top Applications, categories, and so on).

If you'd rather not have certain window titles recorded verbatim (e.g. a password manager showing an account name in its title bar), see Privacy filters — they strip sensitive titles before anything is saved, not just hide them afterward.

Away from keyboard (`aw-watcher-afk`)

Watches keyboard and mouse input (never what you type or click, only whether you're doing so) to tell whether you're actually at your computer. After 3 minutes without any input, you're marked "away" until the next keystroke or click.

This is what "Time active" on the Home page actually means — active time, not just "app open" time. It also determines which parts of the Timeline count toward your work hours.

Some activities don't need any typing or clicking — reading a long document, being on a call, watching something. For those, mark specific apps as "always active" in Settings → Active pattern, so the away-detection doesn't wrongly discount time spent in them.

App icons and names (`aw-watcher-app-icons`)

Not a tracker in its own right — it doesn't record any time. Runs quietly in the background extracting the icon, a friendlier display name, and a representative color for every app TrackFlow sees, so the Timeline and Home modules show something nicer than a bare .exe filename.

VPN sessions (`aw-watcher-vpn`)

Detects when an OpenVPN Connect or ZyWALL SecuExtender connection is active and records it as a session. On its own it only knows an IP address — to see a client's real name in the Timeline, map that address to a name once in Settings → VPN (for OpenVPN Connect, the name is often picked up automatically from the profiles already configured in the program itself). New mappings apply retroactively to sessions already recorded, and the mapping itself refreshes every 15 seconds, so a newly added client shows up almost immediately.

The list of recognized VPN clients may grow over time.

Excel files (`aw-watcher-excel`)

Tracks which Excel files you have open — from the moment a file opens to the moment it closes, independent of which window currently has focus, and correctly handling several files open side by side. Updates in real time (no need to close a file before it shows up).

Turn this off in Watchers → Data sources if you'd rather have Excel tracked like any other app (foreground time only, no per-file detail in its own lane) — it'll then show up in the General lane instead, and the "Top Excel Files" Home module keeps working either way (built from window titles if the dedicated watcher is off).

VS Code (`aw-watcher-vscode`, official extension)

Unlike the others, this one isn't a TrackFlow process — it's the official "ActivityWatch for VSCode" extension, which you install separately from the VS Code marketplace. Once installed, it sends TrackFlow the project and file you're editing, checking roughly every 2 seconds. Powers the "Top Editor Projects/Files" Home modules and the VS Code Timeline lane.

Claude (`aw-watcher-claude-code`)

Records which project you're working on when you use Claude to write code, and for how long.

From the terminal (Claude Code CLI): always tracked.
From the Claude Desktop app: tracked for both Claude Code and Claude Cowork.
Claude Desktop's regular chat (the normal conversation, not for coding) can't be tracked.

Screenshots (`aw-watcher-screenshot`)

Takes a screenshot every 30 seconds by default (configurable in Settings → Screenshot, along with quality and how long to keep them — 14 days by default, older ones deleted automatically). Captures either all monitors combined or only the active window, your choice. Saved into a folder-per-day under TrackFlow's own data folder, viewable from the Screenshot gallery.

Background apps (`aw-watcher-tray`) — off by default

Meant to detect apps running quietly in the system tray. Currently disabled by default: reading hidden tray icons reliably isn't possible yet on Windows 11's newer taskbar. Left in place for when a reliable way to read them is found.