Custom watchers: how they work

Track anything you want — without writing a single line of TrackFlow's own code, and without recompiling anything. This is the easiest way to add a new data source, and the one almost everyone should use.

What a custom watcher actually is

A custom watcher is your own small program or script that TrackFlow runs on a schedule, on your own computer. Every time it runs, it can print a bit of data — a number, a status, a name, whatever you want — and TrackFlow saves it, shows it on your Home page, and lets you export it, exactly like any of the built-in trackers (active window, VS Code, VPN, and so on).

You create, edit, and delete custom watchers entirely from inside the app — no code editor for TrackFlow itself, no rebuilding, no restart of the app required.

Two modes — this guide covers Simple mode

When you create a watcher, TrackFlow asks you to pick one of two modes:

• Simple mode — you write one small script in a language of your choice. TrackFlow re-runs it automatically every so often, reads whatever it printed, and turns that into tracked data for you. You never have to think about buckets, timestamps, or TrackFlow's internal data format. This is what the rest of this guide is about.
• Expert mode — for advanced use: a long-running process you write yourself, following TrackFlow's full internal contract (the same one built-in watchers use). More power, more responsibility, and not covered here.

Where this lives in the app

Everything happens on the Data sources page (the sidebar icon that looks like a database). It shows two tables: the built-in modules TrackFlow ships with, and — further down — every custom watcher you've created, along with a "+ New custom watcher" button right below that second table.

Next: Writing the watcher script.