Skip to content
Saimul Islam

active-window-sessions: turn active-win readings into time per app and website

Turn active-win style polling into clean time segments per app and per website: merges short gaps, drops blips, respects idle time, ignores system UI and totals each app.

Install
npm install active-window-sessions get-windows

Overview

get-windows and active-win tell you which window is in front at one moment. Turning a stream of those readings into reliable time segments is left to you: gaps when the window flickers, blips from a notification, time the user was away, and system UI that is not an app. active-window-sessions does that part, so you can build time tracking and app usage tracking on top of an active-win reading.

It merges short gaps, drops blips, cuts a segment at the last input when the user goes idle, ignores system UI, and adds up the totals per app and per website. The core has no dependencies and takes any sample function. It started as the app-tracking core of the Staffic desktop app.

Examples

Track an Electron app and total it by app and by site
import { app, powerMonitor } from 'electron';
import { aggregate, createTracker, getWindowsSampler } from 'active-window-sessions';
import type { Segment } from 'active-window-sessions';

const segments: Segment[] = [];

const tracker = createTracker({
  sample: getWindowsSampler(),
  getIdleSeconds: () => powerMonitor.getSystemIdleTime(),
  onSegments: (batch) => segments.push(...batch),
});

app.whenReady().then(() => tracker.start());
app.on('before-quit', () => tracker.stop());

// Later, for example for today:
const startOfDay = new Date().setHours(0, 0, 0, 0);
console.log(aggregate(segments, { by: 'app', from: startOfDay }));
console.log(aggregate(segments, { by: 'host', from: startOfDay }));
Run the same rules over samples you already have
import { aggregate, sessionize } from 'active-window-sessions';

const t0 = Date.parse('2026-03-02T09:00:00Z');
const at = (seconds, window, idleSeconds) => ({ at: t0 + seconds * 1000, window, idleSeconds });

const code = { app: 'Code', appId: 'com.microsoft.VSCode' };
const chrome = (url) => ({ app: 'Google Chrome', appId: 'com.google.Chrome', url });

const samples = [
  at(0, code),
  at(2, code),
  at(8, chrome('https://github.com/acme/app/pulls')),
  at(19, chrome('https://github.com/acme/app/issues'), 0),
  at(70, chrome('https://github.com/acme/app/issues'), 51), // idle for 51 s: the last input was at 19 s
];

const segments = sessionize(samples);
console.log(aggregate(segments, { by: 'host' }));
// [ { key: 'github.com', name: 'github.com', durationMs: 11000, segmentCount: 1 } ]

Features

01Merges short gaps
Segments of the same target closer together than 2 seconds become one, so a flicker does not split your time.
02Drops blips
A segment shorter than 1 second is dropped, and a blip between two stretches of the same target does not stop them merging.
03Respects idle time
When idle time reaches 50 seconds the open segment is cut at the last input, not when idle was noticed. A sleeping laptop does not log an hour in the front app.
04Ignores system UI
Notification centers and similar macOS system windows do not end a segment. The default ignore list covers macOS system UI, and you can extend it.
05Per app and per website
The target is the app plus, for browsers, the host. aggregate() totals by app or by host, largest first, for any time range.
06macOS permission helpers
Helpers for Accessibility, Screen Recording and per-browser Automation, in active-window-sessions/macos. They take Electron objects as arguments, so nothing runs until you call it.

Limits

  • It is polling. Segment edges are only as accurate as the interval (2 seconds by default), and a window that comes and goes between two polls is not seen.
  • Only the front window counts. Background tabs, a second monitor, and audio or meeting activity are not detected.
  • Browser URLs come from get-windows, which reads them on macOS only, for the browsers it supports, and only with Accessibility and per-browser Automation granted.
  • Linux works on X11 with xprop and xwininfo installed. Wayland has no active-window API.
  • Idle time comes from the function you pass. Without getIdleSeconds, a user who walks away is counted as active until the window changes or goes stale.
  • The default ignore list covers macOS system UI only. get-windows is never called by this package's tests, so check the adapter on a real machine before you rely on it.

Frequently asked questions

How do I get the active window in Node.js and track time on it?

Reading the window is get-windows, or active-win. This package starts after that: getWindowsSampler() wraps get-windows, createTracker() polls it every 2 seconds, and your onSegments callback receives finished time segments. toWindowInfo() converts an active-win result if you call it yourself.

How do I track time spent on apps and websites?

Call aggregate(segments, { by: "app" }) or { by: "host" }. You get a total in milliseconds and a segment count for each app or site, largest first. Hosts need a browser that get-windows can read, which means macOS with Accessibility and Automation granted.

What does it store, and is it an app usage tracker?

It is a library for building an app usage tracker, not an app. A segment holds the app name, an app identifier, the host of a browser URL and start and end times. Paths and query strings are dropped, window titles are never stored, and the library makes no network requests.

Does it work on Windows and Linux?

The segmenting core is plain JavaScript and runs anywhere. Window reading depends on get-windows: Linux needs X11 with xprop and xwininfo, and Wayland has no active-window API. The macOS permission helpers do nothing off macOS.

  • Maps and GPS

    gpx-privacy

    Make GPX tracks safe to share: trim the start and end, simplify the track, compute distance and climb, and write a minimal clean GPX file.

  • AI agents

    mcp-guardrails

    AI agent guardrails for MCP servers: dry run and confirm, signed preview tokens, optimistic concurrency, revision undo and errors that teach the agent.

See all 9 open-source packages

Author

Built by Saimul Islam

Saimul Islam is a Forward Deployed Engineer and Solutions Architect. Several of these packages run in production on DeveloperLook, the Bundlewise CRM and Sitessa.